fix(rust): Centralize FixedSizeList outer-to-child layout arithmetic and fix under-reservation - #28993

Closes #28979
Resolves #28872

Core Problem & Background

In Polars and Arrow, FixedSizeList operates simultaneously across two distinct coordinate spaces:

1. Outer units (List level): Number of list items / rows (e.g., reserving space for $N$ lists, row offset $i$, slice length $L$).
2. Child units (Inner buffer level): Number of flattened primitive elements in the underlying leaf storage (inner_builder or values), where each outer list item contains $K$ child elements ($K = \text{width} = \text{size}$).

$$\text{Child Offset} = \text{Outer Offset} \times \text{size}$$ $$\text{Child Length} = \text{Outer Length} \times \text{size}$$

Because both outer and child counts are represented as primitive usize integers, unit mismatch is invisible to the Rust compiler. Passing an outer unit where a child unit is expected compiles without warning or type error.

The Failure Mode (#28872)

In FixedSizeListArrayBuilder::reserve and MutableFixedSizeListArray::reserve:

// BEFORE:
fn reserve(&mut self, additional: usize) {
    self.inner_builder.reserve(additional); // Under-reserves child storage!
    self.validity.reserve(additional);
}

What went wrong:

• additional is in outer list units.
• self.validity.reserve(additional) is correct because the validity bitmap is indexed per outer list slot.
• self.inner_builder.reserve(additional) is wrong because inner_builder stores child elements. Reserving only additional child slots instead of additional * self.size allocates only $\frac{1}{\text{size}}$ of the required storage.

Concrete Example:

For a FixedSizeList with width $K = 16$:

• Reserving $N = 1{,}000$ outer rows asked the inner child builder to reserve only $1{,}000$ child items instead of $16{,}000$.
• Because Rust dynamic vectors reallocate automatically on push, this bug did not produce incorrect computational results, but it completely defeated pre-allocation and forced the inner builder to repeatedly trigger expensive reallocations, memory copies, and vector resizes during appends.

Design & Solution

Instead of scattering raw outer * self.size multiplications across operations (where omissions can easily happen again), this PR centralizes all coordinate arithmetic into explicit conversion primitives.

1. Centralized Primitives

Introduced child_offset and child_length in crates/polars-arrow/src/array/fixed_size_list/mod.rs:

#[inline(always)]
pub(crate) const fn child_offset(outer_offset: usize, size: usize) -> usize {
    outer_offset * size
}

#[inline(always)]
pub(crate) const fn child_length(outer_length: usize, size: usize) -> usize {
    outer_length * size
}

2. Fixed Builders Pre-Allocation

Updated reserve in both builders to convert outer units before delegating to the child buffer:

• FixedSizeListArrayBuilder:

  fn reserve(&mut self, additional: usize) {
      self.inner_builder.reserve(child_length(additional, self.size));
      self.validity.reserve(additional);
  }

• MutableFixedSizeListArray:

  pub fn reserve(&mut self, additional: usize) {
      self.values.reserve(child_length(additional, self.size));
      if let Some(x) = self.validity.as_mut() {
          x.reserve(additional);
      }
  }

Verification

Added Regression Tests

1. crates/polars/tests/it/arrow/array/fixed_size_list/mutable.rs:
   • test_reserve: Verifies that MutableFixedSizeListArray::reserve(10) with width 3 allocates at least 30 child units in the underlying buffer.
2. crates/polars/tests/it/arrow/array/fixed_size_list/mod.rs:
   • test_builder: Tests FixedSizeListArrayBuilder end-to-end (pre-allocation with reserve, extend_nulls, subslice_extend, and freeze_reset).

Test Results

cargo test -p polars --test it fixed_size_list